package net.sourceforge.openclixml.environment;


/**
 * An environment is a set containing variables an can extend other variables.
 * A variable consists of a key and a value. The environment can resolve variables. If the variable (they key of it) is not defined in this variable, the resolution is forwarded to the extended environment. If the environemnt extends no other environemnt and no key is found an exception will be thrown. This model corresponds to the described by Abelson and Sussmann in their Scheme book.
 * @param <KeyType> type of the key set
 * @param <ValueType> the of the value set
 * @version $Revision: 47 $
 * @author dominikjungo
 *
 * Last changed: $Date: 2008-02-03 22:01:31 +0100 (Sun, 03 Feb 2008) $
 * The License for this file can be found in doc/Licenses/license-OpenCliXML.txt
 */
public interface IEnvironment<KeyType, ValueType> {
    /**
     * Extends the environment with a new variable and corresponding value.
     * @param variableName the variable name
     * @param value the variable's value
     */
    void add(KeyType variableName, ValueType value);

    /**
     * Extends this environment with a new empty environment.
     * @return the empty environment which extends this environment
     */
    IEnvironment<KeyType, ValueType> extend();

    /**
     * Extends this environment with a new environment and sets a variable in the new environment.
     * @param variableName the variable name
     * @param value the variable's value
     * @return the environment which extends this environment
     * @see #add(Object, Object)
     */
    IEnvironment<KeyType, ValueType> extend(KeyType variableName,
        ValueType value);

    /**
     * Resolves a variable. If the variable is not found in this environemnt, a recursive lookup in the extended environments is performed.
     * @param value the variable name
     * @return the variable's value in the outermost environment
     * @throws VariableNotFoundException if no variable was found in this and the extended environments was found.
     */
    ValueType resolve(KeyType value) throws VariableNotFoundException;

    /**
     * Resolves an XPath expression to an Entry.
     * @param xpath the xpath to resolve
     * @return the resolved entry found at the xpath.
     */
    ValueType resolveXPath(KeyType xpath);
}
